home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / system / xpcmou10.zip / xpcmouse.doc < prev    next >
Text File  |  1994-12-16  |  34KB  |  749 lines
  1.  
  2. XPCMOUSE.DOC
  3.  
  4.            documentation for xPC-Mouse Version 1.0: 3-Dec-1994
  5.             Position Cursor, Copy and Paste in Dos Text Mode
  6.  
  7.      Copyright (c) 1994 by Jürgen G. Weber and Grant B. Gustafson.
  8.                           ALL RIGHTS RESERVED
  9.  
  10. NO COST?
  11.    This software is provided free of charge to individuals and educational
  12.    institutions. Money is not requested.
  13.    Free for personal use under the Gnu Public License agreement, which
  14.    is distributed with this source.
  15.  
  16. POSTCARDS?
  17.    Postcards and comments are welcome!
  18.  
  19.    Jürgen G. Weber               GB Gustafson
  20.    Wiesentalstraße 1             113 JWB Math Dept Univ Utah
  21.    D-74523 Schwäbisch Hall       Salt Lake City, UT 84112
  22.    Germany - European Union      USA
  23.  
  24. NO WARRANTY.
  25. The authors do not warrant the correctness of the documentation or the
  26. function of the program. They do not warrant uninterrupted or error free
  27. operation of the Program.
  28.  
  29. The user is advised to test the program fully. The risk of using this
  30. software is exclusively with the user. The author assumes no liability
  31. whatever for damages of any kind that might result from using the
  32. program.
  33.  
  34. Cited product names are trade names.
  35.  
  36. ========================== GNU PUBLIC LICENSE ==========================
  37.  
  38.    This software is released as copyrighted material under the GNU
  39.    PUBLIC LICENSE:
  40.                               NO WARRANTY
  41.    Because xPC-Mouse is licensed free of charge, absolutely no warranty
  42.    is provided, to the extent permitted by applicable state law.  Except
  43.    when otherwise stated in writing, Jürgen G. Weber and Grant B.
  44.    Gustafson provides xPC-Mouse "as is" without warranty of any kind,
  45.    either expressed or implied, including, but not limited to, the
  46.    implied warranties of merchantability and fitness for a particular
  47.    purpose. The entire risk as to the quality and performance of the
  48.    program is with you. Should the xPC-Mouse program prove defective,
  49.    you assume the cost of all necessary servicing, repair or correction.
  50.  
  51.    In no event unless required by applicable law will Grant B. Gustafson
  52.    and Jürgen G. Weber and/or any other party who may modify and
  53.    redistribute xPC-Mouse be liable to you for damages, including any
  54.    lost profits, lost monies, or other special, incidental or
  55.    consequential damages arising out of the use or inability to use
  56.    (including but not limited to loss of data or data being rendered
  57.    inaccurate or losses sustained by third parties or a failure of the
  58.    program to operate with programs not distributed by Grant B.
  59.    Gustafson and Jürgen G. Weber) the program, even if you have been
  60.    advised of the possibility of such damages, or for any claim by any
  61.    other party.
  62.  
  63.  
  64. ============================= INTRODUCTION =============================
  65.  
  66. The TSR program xPC-Mouse enables Position, Copy and Paste in the text
  67. modes of PC video cards. Programs that use the mouse themselves work as
  68. usual and ignore the presence of xPC-Mouse.
  69.  
  70. REMOTE UNIX HOST
  71.  A useful installation of xPC-Mouse is on a DOS machine running
  72.  MS-kermit 3.xxx over a 9600/14400 baud modem to a remote unix host.
  73.  Most of the very useful mouse functions familiar to Xterm users will be
  74.  available, especially double-click and paste for unix file names,
  75.  cursor positioning on the command line and in text editors (emacs, vi,
  76.  jove, jed, pi), and copy/paste of local text and remote host text.
  77.  
  78. LOCAL COPY/PASTE
  79.  Local use on a PC includes the familiar need to capture error messages
  80.  off the screen, to be pasted into a text editor, or the copying of file
  81.  names, to be pasted on to the command line. Unix users of Xwindows will
  82.  find the mouse functions useful and natural.
  83.  
  84. PC EDITORS
  85.  Most PC text editors can use xPC-Mouse to position the cursor and
  86.  copy/paste small selections of text. This is especially useful in
  87.  special-purpose editors, like the Czech TeX User's group editor called
  88.  CSED, which uses the Latin II character set. The xPC-Mouse TSR works
  89.  with this editor in text mode, for example, EGA monochrome. Similar
  90.  statements apply to epsilon, emacs, qedit, jed, pi, and vi clones. The
  91.  Xterm mode can be used with extensible editors to produce a seamless
  92.  interface to the editor's own copy/cut/paste/position functions.
  93.  
  94. ======================= HARDWARE/SOFTWARE NEEDED =======================
  95.  
  96. HARDWARE
  97.  
  98.   8088 CPU or better (80286, 80386, 80486)
  99.   Modern Bios (1985 or later), IBM compatible
  100.   Microsoft compatible mouse with 2 or 3 buttons
  101.  
  102. SOFTWARE
  103.  
  104.   New mouse device driver MOUSE.SYS, e.g., from MS Windows
  105.       Normally loaded from the file CONFIG.SYS. See below.
  106.   MS-DOS compatible operating system
  107.       Tested with MS-DOS 5.0, SoftPC on a SUN4, OS/2 2.x Dos Emulation.
  108.  
  109. CONFIG.SYS and AUTOEXEC.BAT
  110.  
  111.   There must be a line DEVICE=MOUSE.SYS or similar, unless a TSR program
  112.   load of MOUSE.EXE or MOUSE.COM appears in AUTOEXEC.BAT.
  113.  
  114.   Recommended is a line STACKS=9,256 because of the patch to int 21h
  115.   function 4bh. See STACKS below and the discussion of interrupts. Most
  116.   systems run with the MSDOS default STACKS. Problems may emerge with
  117.   deeply nested batch files but not with ordinary operation.
  118.  
  119. WINDOWS
  120.  
  121.   The action taken by windows is to disable any mouse hooks when it
  122.   starts. So don't expect xPC-Mouse to work inside windows. It WILL work
  123.   in a full screen DOS window. It is especially NOT RECOMMENDED to load
  124.   xPC-Mouse in a DOS window --- load it in DOS BEFORE entering windows.
  125.   If previously loaded, then attempts to load it again will fail, which
  126.   is exactly what you would want in Windows.
  127.  
  128.   In particular, if you like to run kermit from Windows and like
  129.   xPC-Mouse to be there, then load xPC-Mouse from the DOS prompt before
  130.   entering windows.
  131.  
  132. xPC-Mouse complains if you lack anything essential. The error messages
  133. are explained below in a separate section.
  134.  
  135.  
  136. =============================== PACKAGE ================================
  137.  
  138. The package consists of:
  139.  
  140.   XPCMOUSE  DOC   : the file you are reading
  141.   XPCMOUSE  ASM   : Source code for TASM/TLINK (Borland Intl)
  142.   XPCMOUSE  EXE   : xPC-Mouse executable for DOS (a TSR program)
  143.  
  144. ============================HOW TO USE xPC-Mouse==========================
  145.  
  146. Typical command lines:
  147.  
  148.                 XPCMOUSE /a2            Use matrix method for cursor
  149.                                         positioning (default is /A1)
  150.  
  151.                 loadhigh XPCMOUSE       Use UMB's to save lower memory.
  152.  
  153.                 XPCMOUSE /H             Display mouse button assignments
  154.  
  155. If xPC-Mouse is not installed and ? appears on the command line, then it
  156. aborts installation and prints the help screen:
  157.  
  158.  
  159. xPC-Mouse, version 1.0: 3 Dec 1994
  160. Copyright (c) 1994 Jürgen G. Weber and G.B. Gustafson
  161. Free for personal use under the Gnu license agreement.
  162.  
  163. Options: /U    : Un-install xPC-Mouse
  164.          /Q    : Quiet, no messages
  165.          /R    : Re-activate xPC-Mouse
  166.          /M    : Monochrome video mode (equals /X119)
  167.          /Xddd : Highlight XOR mask ddd (default /X80)
  168.          /Bddd : Buffer size ddd paragraphs (16*ddd bytes)
  169.          /T    : Enable timer int 1Ch patch
  170.          /N    : Defeat int 21h patch
  171.          /P    : Defeat pastebuffer use
  172.          /K    : Defeat arrow key emulation
  173.          /A1   : Emacs/vi arrow key method (default)
  174.          /A2   : Matrix arrow key method
  175.          /A3   : Xterm escape sequence method
  176.  
  177. Info:    /C    : Display copying information
  178.          /?    : Display help text
  179.          /H    : Display mouse button assigments
  180.  
  181.  
  182. If xPC-Mouse was already installed, or this is the first install, then
  183. the appropriate message is displayed, for example:
  184.  
  185. xPC-Mouse, version 1.0: 3 Dec 1994
  186. Copyright (c) 1994 Jürgen G. Weber and G.B. Gustafson
  187. Free for personal use under the Gnu license agreement.
  188.  
  189. Info:    /C    : Display copying information
  190.          /?    : Display help text
  191.          /H    : Display mouse button assigments
  192.  
  193. MOUSE BUTTON             FUNCTION
  194. Mouse 1 (1/6 second) ... Position cursor
  195. Mouse 2 ................ Paste text
  196. Drag Mouse 1 ........... Copy text
  197. Double-click Mouse 1 ... Copy word
  198. CTRL-Mouse 2 ........... Paste text + ENTER
  199. ALT-Mouse 2 ............ Mouse 3 duplicate
  200. SHIFT-Mouse 1 .......... Cursor feature on/off
  201. SHIFT-ALT-Mouse 1 ...... Toggle methods /A1-/A3
  202. SHIFT-Mouse 2 .......... Paste feature on/off
  203.  
  204. xPC-Mouse was already installed.
  205.  
  206. If you do not use the mouse you will see no sign of xPC-Mouse being
  207. present. When you move the mouse, the mouse cursor appears. It gets
  208. hidden again as soon as the next character is displayed on screen.
  209.  
  210.  
  211. =========================== COMPILER EXAMPLE ===========================
  212.  
  213. Example. Use xPC-Mouse to drag compiler error messages into an editor.
  214.  
  215.   The compiler is run as an editor shell. The messages appear on the
  216.   screen, but are lost as soon it the editor is re-entered:
  217.  
  218.   Assembling file:   TEST.ASM
  219.   **Error** TEST.ASM(165) Undefined symbol: MAINEXIT
  220.   **Error** TEST.ASM(190) Undefined symbol: EXITLOOP1
  221.   Error messages:    2
  222.   Warning messages:  None
  223.   Remaining memory:  470k
  224.  
  225.   Solution: Copy the text needed into the paste buffer using the mouse.
  226.             Pop back into the text editor and paste the copied text into
  227.             a scratch buffer or as comments at the top of the current
  228.             source file. The messages can be analyzed from the
  229.             reference.
  230.  
  231. ========================== DIRECTORY EXAMPLE ===========================
  232.  
  233. Example. Use xPC-Mouse to copy a directory listing into an editor.
  234.  
  235.   Most editors allow a shell to DOS to do a directory, but offer no
  236.   features for pasting the information back into the file being
  237.   edited. With xPC-Mouse, copy the desired text to the paste buffer and
  238.   re-enter the editor. Then paste with the mouse.
  239.  
  240.  
  241. ========================= COMMAND LINE EXAMPLE =========================
  242.  
  243. Example. Use xPC-Mouse to copy and paste file names onto the command
  244.          line.
  245.  
  246.   Many command lines take several file names, usually already on the
  247.   screen due to a directory listing.  GNU software like "ls" is useful
  248.   for displaying the filenames in a compact and directly usable format.
  249.  
  250.   The method used with xPC-Mouse is to DOUBLE-CLICK on a file name. That
  251.   places the file name in the paste buffer. Then press the right mouse
  252.   button to paste onto the command line.
  253.  
  254.  
  255. =========================== MOUSE OPERATIONS ===========================
  256.  
  257.     HIGHLIGHT text by dragging the left button.
  258.  
  259. To select a text area move the mouse cursor to the beginning of the
  260. area. Keep the left button pressed and move over the area you want to
  261. select. When you release the left button the selected text is copied to
  262. xPC-Mouse's internal buffer. If you select a new screen area the internal
  263. buffer is overwritten.
  264.  
  265.  
  266.     DOUBLE-CLICK on the left button highlights one word.
  267.  
  268. If the mouse cursor is on a word you can select it by double clicking
  269. the left button. A word is a sequence of letters, digits, the underline
  270. character and European special letters (IBM ascii values 80h to 0a5h,
  271. 0e0h to 0ebh). This TSR has been coded to accept most unix file names.
  272.  
  273.  
  274.     PASTE the highlighted text by clicking the right button.
  275.  
  276. Press the right mouse button to simulate the content of the buffer being
  277. typed at the keyboard. If you keep the CONTROL key pressed while
  278. pressing the right button, an additional pressing of ENTER is simulated.
  279.  
  280.  
  281.     SET CURSOR by pressing the left button 1/6 second.
  282.  
  283. If you press and release the left button without selecting an area the
  284. cursor is positioned to that location, by stuffing the keyboard buffer
  285. with appropriate arrow keys. However, the press must be 1/6 second or
  286. longer before release, or nothing happens. This is how double-click is
  287. distinguished from just a left button press intended to position the
  288. cursor.
  289.  
  290.  
  291.     TOGGLE the set cursor feature by pressing SHIFT left button
  292.  
  293. The set cursor function can sometimes send unwanted characters to a
  294. program. Hold down the SHIFT and press the left button, then
  295. release both, to toggle the feature on/off. The copy and paste will both
  296. work with the set cursor function defeated. To disable the set cursor at
  297. startup, use the /K option on the command line (see below).
  298.  
  299.  
  300.     TOGGLE the paste feature by pressing SHIFT right button
  301.  
  302. The paste function can sometimes send unwanted characters to a program.
  303. Hold down the SHIFT and press the right button, then release both, to
  304. toggle the feature on/off. The cursor positioning functions will still
  305. work with the copy/paste functions defeated. To disable the copy/paste
  306. at startup, use the /P option on the command line (see below).
  307.  
  308.  
  309.     TOGGLE the /A1-/A3 options by pressing SHIFT-ALT left button
  310.  
  311. These methods can be selected at startup (/A1 is the default). Some
  312. remote applications may not use the method effectively, e.g., menu
  313. systems such as found in GOPHER on the internet will not respond
  314. properly to /A1 or /A3. The options are toggled one at a time in the
  315. order
  316.                       /A1 --> /A2 --> /A3 --> /A1
  317.  
  318. The methods /A1-/A3 can be disabled by the /K option on startup or
  319. changed dynamically by pressing SHIFT button 1.
  320.  
  321.  
  322.     Transmit Button 3 by pressing ALT button 2
  323.  
  324. Some remote applications may need a third mouse button press. Even if
  325. you only have a 2-button mouse, this is possible. The third button on a
  326. 3-button mouse (usually the middle button) does the same thing as ALT
  327. button 2.
  328.  
  329.  
  330. DE-SELECTION. The selected area is de-selected as soon as you press the
  331. left key again or if anything is displayed on the screen. This is done
  332. because the programs you run don't know anything about the selection.
  333. The de-selecting is done to prevent chaos on the screen. Optical harm
  334. may be caused by xPC-Mouse running together with programs that use page
  335. swaps to achieve fast refresh. It's not dangerous.
  336.  
  337. MOUSE SUPPORT. If a program offers mouse support itself the mouse
  338. functions of xPC-Mouse lay dormant until the program ends. Clearly not
  339. both can run at the same time, so xPC-Mouse is put in the background by
  340. such programs. After the program exits, xPC-Mouse comes alive again.
  341.  
  342.  
  343. =========================== COMMAND LINE OPTIONS ==========================
  344.  
  345.          /U    : Un-install xPC-Mouse
  346.                Removes mouse driver from memory and resets all affected
  347.                interrupt vectors. Finally, it resets the manufacturers
  348.                mouse driver.
  349.  
  350.          /Q    : Quiet: no messages
  351.                All messages omitted on startup.
  352.  
  353.          /R    : Re-activate xPC-Mouse
  354.                Some programs reset the manufacturers mouse driver and
  355.                un-vector previous mouse programs. After exit from them,
  356.                xPC-Mouse may need to be restarted.
  357.  
  358.          /Xddd : XOR screen mask ddd (default /X80)
  359.                The highlight of a screen area is indicated by XORing the
  360.                attribute bytes with ddd=80, to de-select they are simply
  361.                XORed again. Normally the XOR mask is 80. A useful one
  362.                for monochrome is ddd=119. With ddd=0 you get no visible
  363.                selection.
  364.  
  365.          /Bddd : Buffer size ddd paragraphs (16*ddd bytes)
  366.                The buffer size can be set to any size less than the
  367.                pre-compiled size. The syntax "xPCmouse /B128" sets the
  368.                buffer size to 16*128 == 2048 bytes. To use the default
  369.                size, no command line option is required. A common
  370.                setting is "xPCmouse /B0 /P" which reduces the paste
  371.                buffer size to 0 and defeats all pasting operations.
  372.                Memory use is reduced by 2k.
  373.  
  374.          /M    : Monochrome video mode
  375.                Same as /X119. Works on Hercules mono cards.
  376.  
  377.          /N    : Defeat int 21h patch
  378.                The int 21h patch may interfere with certain software.
  379.                Or, system stack may be insufficent to support the
  380.                function calls made in this int 21h patch. If you use
  381.                this, then /R is required to jump-start xPCMouse after
  382.                exit from certain programs.
  383.  
  384.          /T    : Enable timer int 1Ah patch
  385.                May be needed for certain applications that use strange
  386.                keyboard input instead of int 16h or int 21h functions.
  387.  
  388.          /K    : Defeat Arrow key emulation
  389.                The left button pressed for 1/6 second normally produces
  390.                a stuffing of arrow keys to reset the text cursor to the
  391.                button press location. This command line option causes
  392.                xPC-Mouse to start up with that feature defeated. Holding
  393.                the SHIFT key down and pressing the left button toggles
  394.                the /K state on/off.
  395.  
  396.          /P    : Defeat pastebuffer use
  397.                Some applications will not allow pasting, since the
  398.                application does it already in response to Xterm
  399.                sequences that emulate the mouse buttons. Also used to
  400.                simplify logic for paste buffer size 0 (see /B0).
  401.  
  402.          /A1   : Emacs/vi arrow key method (default)
  403.          /A2   : Matrix arrow key method
  404.          /A3   : Xterm escape sequence method
  405.                The matrix method positions the cursor by moving it by
  406.                columns first, then by rows. The Emacs method moves the
  407.                cursor first to column 0, then the matrix method is
  408.                applied. This prevents false positioning due to emacs
  409.                character-stream notions of "point". Also works in VI,
  410.                JOVE and JED. The Xterm method sends escape sequences
  411.                recognized by Xterm as simulations of the mouse. Many
  412.                editors already recognize the escapes, but may need
  413.                additional support to make full use of the information.
  414.                The Xterm support is the best for modem use. See the
  415.                technical notes below for more detail.
  416.  
  417.          /C    : Display copying information
  418.                Prints the author addresses, email addresses and
  419.                copyright information for the GNU license agreement.
  420.  
  421.          /?    : Display help text
  422.                Actually, any nonsense on the command line causes help to
  423.                be printed as does any command line containing a question
  424.                mark.
  425.  
  426.          /H    : Display mouse button assigments
  427.                This display can be obtained without loading the TSR. By
  428.                default, it is displayed if the driver is already
  429.                resident, since in this situation, mouse button
  430.                information is more relevant than command line switches.
  431.  
  432.  
  433. ========================== MONOCHROME CARDS ===========================
  434.  
  435. On monochrome systems (Hercules compatible cards) you could try option
  436. /X119 to produce a visible selection on screen. The special option /M is
  437. a synonym for /X119. If the command line has no /X or /M options, then a
  438. check is made for for video mode 7 (mono monitor). If found, then the
  439. TSR selects /M automatically.
  440.  
  441. So switches /X119 or /M are useful only if the computer fools the
  442. software and you need a manual over-ride. This happens, for example, on
  443. laptop computers with mono EGA/VGA. The check for text mode 7 will not
  444. be successful on such hardware.
  445.  
  446.  
  447. =========================== TECHNICAL NOTES ============================
  448.  
  449. KEYBOARD STUFFING /A1 AND /A2.
  450. Cursor keys are stuffed into the keyboard by options /A1 and /A2.
  451. Precisely, the scan codes for these keys are stuffed. Logic is applied
  452. to keep from over-running the keyboard buffer. There are 4 cursor key
  453. scan codes possible. Option /A1 tests to see if the target row is the
  454. same as the present text cursor row. If it isn't, then the text cursor
  455. is first moved to column 1. Option /A1 then moves by the MATRIX METHOD:
  456. move the cursor to the target row, then to the target column. Option /A2
  457. is /A1 with the normalization to column 1 removed; it is the matrix
  458. method.
  459.  
  460.  
  461. KEYBOARD STUFFING /A3.
  462. In option /A3, X-Windows X10 compatibility mode is assumed. However,
  463. no escape sequences from DECSET 9 are sent to the host. That is left
  464. to the host program or the user. We stuff an escape sequence on each
  465. button press encoding the location and the mouse button pressed. In this
  466. mode, we assume the keyboard buffer is emptied quickly, in order to
  467. simplify the logic for stuffing 6 or 12 scan codes at once. We don't
  468. know how this works in practise across all machines, let us know!
  469.  
  470. On button press, xPC-Mouse in mode /A3 sends ESC [ M Cb Cx Cy, a total
  471. of characters, 12 bytes of scan code data.  The variables are as
  472. follows:
  473.                Symbol   Coding Rules
  474.  
  475.                Cb       32 == Button 1 [left button]
  476.                         33 == Button 2 [right button]
  477.                         34 == Button 3 [middle button]
  478.  
  479.                Cx       32+X, X == mouse row, 1 <= X <= 25
  480.                Cy       32+Y, Y == mouse column, 1 <= Y <= 80
  481.  
  482. Example: Char   Decimal  Coded Info
  483.  
  484.          ESC     27      Lead-in byte1
  485.          [       91      Lead-in byte2
  486.          M       77      Lead-in byte3
  487.          !       33      Button 2
  488.          *       42      Row 10
  489.          U       85      Col 53
  490.  
  491. Mouse DRAG holds down the left button with release in a new location.
  492. This results in two escape sequences, the first for button 1 at the
  493. location where the drag began, and the second for button 3, at the
  494. location of release. This sequence can be done without dragging by
  495. pressing button 1 and then ALT-button 2 (alias for button 3, for
  496. 2-button mouse).
  497.  
  498. The Xterm X10 standard for highlighting a region uses a press of button
  499. 1 followed by a press of button 3. During this marking stage, no
  500. highlight appears. Editors like Emacs make use of this method under
  501. X-Windows, but indeed highlight the text upon receipt of the button 3
  502. escape. Newer versions of emacs for Xwindows allow mouse drag and
  503. highlighting features.
  504.  
  505. In any case, the editor must be aware of the button press simulation via
  506. escape sequences. For Emacs, this means that keymaps have been set up
  507. with specific actions, in short, someone has to write the elisp source
  508. to process the escape sequences. Ditto for JOVE, QEDIT, JED and similar
  509. extensible editors. Non-extensible editors have to be extended and
  510. recompiled.
  511.  
  512. A way to understand /A3 is to imagine each button press resulting in the
  513. transmission of a string, like "HELLO, " for button 1, "WORLD." for
  514. button 2 and " BITTER" for button 3. Then pressing button 1, button 2
  515. and button 3 gives "HELLO, WORLD. BITTER" whereas DRAG on button 1
  516. followed by button 2 gives "HELLO, BITTER WORLD.". (During testing, the
  517. ASM code was modified to do something similar, to allow tracing of
  518. escape sequences.)
  519.  
  520.  
  521. PASTE BUFFER.
  522. The paste buffer has space for 2048 characters. The last part is
  523. discarded if the selection is too large. Blanks in a line are compressed
  524. and blanks at the end of a line are discarded. After the last non-blank
  525. of a line xPC-Mouse inserts a CR char to simulate pressing ENTER.
  526. Control characters with ascii values below 32 are not stored in the
  527. buffer and discarded.
  528.  
  529. The paste buffer size can be increased by changing "BUFFERLEN EQU 2048"
  530. in the ASM source to a larger multiple of 16, e.g., 4096. Then the EXE
  531. file will bump its size by 2k and the initial load of the TSR will have
  532. enough space in its code segment (== data segment) for a 4096 paste
  533. buffer. Dynamic buffer sizing /Bddd allows sizing of the paste buffer
  534. from 0 byte to 4096 bytes, where ddd is the decimal (base 10) value in
  535. paragraphs, i.e., /B192 means buffer size 16*192 or 3072 bytes.
  536.  
  537. Stuffing of the paste buffer into the keyboard buffer is done by testing
  538. for sufficent space prior to stuffing the character. Ditto for stuffing
  539. cursor keys and Xterm escapes.
  540.  
  541.  
  542. INTERRUPTS.
  543. xPC-Mouse hooks interrupts 10h, 1ch, 16h and 21h. We explain each one.
  544.  
  545. Int 10h is hooked to de-select a selected screen region every time a
  546. program calls int 10h. The decision is made by a code segment variable,
  547. which records whether or not a screen segement has been highlighted.
  548.  
  549. Int 1ch is hooked to stuff the keyboard buffer on every timer tick, 18.2
  550. per second. This patch affects the pastebuffer and methods /A1, /A2 and
  551. /A3. Initially the patch is defeated. To enable it, use /T on the
  552. command line.
  553.  
  554. Int 16h is hooked to read from xPC-Mouse's buffer. It also gets a new
  555. function 80h that xPC-Mouse uses to see if it is already installed. This
  556. function modifies register AH by decrementing it and it returns in BX
  557. the offset of the paste buffer, in ES the segment of the paste buffer.
  558.  
  559. Int 21h is patched in order to keep xPC-Mouse alive after each program
  560. exit. The only int 21h funtion affected is 4bh (exec program).
  561.  
  562. When a program is executed, int 21h, function 4bh is called, at which
  563. time the patch is invoked. It grabs the far address and event mask of
  564. the installed mouse handler, then saves it on the stack. The mouse
  565. handler for xPC-Mouse is re-installed, just in case COMMAND.COM invoked
  566. the program load. Then the program is run as usual. After exit from the
  567. program, the save mouse routine (on the stack) is activated via int 33h.
  568.  
  569. So xPC-Mouse works at the normal dos prompt and also with dos shells
  570. started within user programs. The saving of the mouse handler on the
  571. stack is necessary because programs can call each other recursively.
  572.  
  573. In particular, xPC-Mouse works with COMMANDO and WCED command line
  574. editors. In these programs, xPC-Mouse adds cursor positioning on the
  575. command line, double-click on file names and pasting of file names onto
  576. the command line at the text cursor position.
  577.  
  578.  
  579. STACKS SETTING.
  580. But this means xPC-Mouse takes some system stack. So if your system does
  581. not work with xPC-Mouse, try the following in CONFIG.SYS
  582.  
  583.                               STACKS=9,256
  584.  
  585. If that does not help, try option /N. This disables the Int 21h patch.
  586. But this means that if a program uses the mouse itself and does not
  587. restore the previous handler xPC-Mouse is no longer active. So you have
  588. to reactivate xPC-Mouse again using xpcmouse /R
  589.  
  590.  
  591. KEYBOARD INTERRUPTS.
  592. Every time a program calls the keyboard interrupt 16h, xPC-Mouse fills
  593. up the keyboard buffer with characters from its internal buffer. As some
  594. programs bypass int 16h and read directly from the keyboard buffer you
  595. can specify option /T so that xPC-Mouse's buffer is stuffed into the
  596. keyboard buffer at every timer tick, too. This option hooks int 1ch. In
  597. general, /T is NOT RECOMMENDED because it steals a lot of CPU time.
  598.  
  599.  
  600. UN-INSTALL.
  601. Use option /u to un-install xPC-Mouse. But this is only possible, if
  602. there is no other TSR loaded after xPC-Mouse that hooks the same int
  603. vectors. If LOADHIGH is used to load xPC-Mouse, then /U works in more
  604. situations, eg, you can shell out of a text editor to kill the TSR.
  605.  
  606.  
  607. EXTENDED TEXT MODES.
  608. xPC-Mouse believes an extended text mode to be active if a video mode
  609. with a higher mode number than the highest in standard vga (=13h) is
  610. active and if a text page needs between 800h and 4000h bytes.
  611.  
  612.  
  613. MEMORY USAGE.
  614. With arrow key emulation and full size paste buffer the size is 4.6k.
  615. xPC-Mouse uses 2k for its text buffer, making resident code sizes of
  616. 2.6k to 4.6k possible. There is a sizable non-resident portion of
  617. xPC-Mouse that contains error messages, help screens, etc. These are not
  618. left in memory, therefore the disk size of xPC-Mouse does not tell you
  619. how much memory it uses.
  620.  
  621. Recompile and editing of xPC-Mouse to remove the paste buffer features
  622. can permanently reduce memory usage to about 2.2k. Since command line
  623. switches are capable of producing memory size 2.6k, there appears to be
  624. no reason to edit and recompile such a special version.
  625.  
  626.  
  627. HIGHLIGHTING METHOD.
  628. The selecting of a screen area is indicated by XORing the attribute
  629. bytes with 80, to de-select they are simply XORed again. To use another
  630. value use the /Xddd option. With ddd=0 you get no visible selection.
  631. Value /X119 is recommended for monochrome. See the /M option.
  632.  
  633.  
  634. ============================ RETURN VALUES ==============================
  635.  
  636.                0  successfully installed
  637.                1  hardware/software requirements failed
  638.                2  already installed
  639.                3  Help request processed, no operations done
  640.  
  641. =========================== ERROR MESSAGES ==============================
  642.  
  643.     xPC-Mouse was already installed.
  644.        Tried to install xPC-Mouse program twice, failure, the program
  645.        will not be installed twice.
  646.  
  647.     xPC-Mouse was not installed yet.
  648.        Tried to re-install xPC-Mouse, failure, because the program was
  649.        not installed.
  650.  
  651.     xPC-Mouse is un-installed.
  652.        Successful /U option de-installs xPC-Mouse and frees memory.
  653.  
  654.     xPC-Mouse is re-activated.
  655.        Successful /R option resets all interrupt vectors and restarts
  656.        the driver.
  657.  
  658.     Could not un-install xPC-Mouse.
  659.        Unsuccessful /U option, because another TSR program was installed
  660.        after xPC-Mouse, or else something went wrong and address
  661.        conflicts were found.
  662.  
  663.     No mouse driver found or driver too old.
  664.        The mouse program supplied with the mouse by the manufacturer is
  665.        not installed or else has a very old version with missing mouse
  666.        driver features. Fix: install the driver in config.sys (then
  667.        reboot) or in autoexec.bat (and type the same command line at the
  668.        dos prompt). If you can't find one, then search the Windows
  669.        directory on a computer with MS-windows. That one might work. If
  670.        you own a non-microsoft mouse, then that could be a problem.
  671.  
  672.     xPC-Mouse not installed.
  673.        Attempt to install xPC-Mouse in memory failed, due to something
  674.        missing, like the mouse driver, or not enough space, or some
  675.        conflict.
  676.  
  677.     xPC-Mouse needs at least an 80286 with extended keyboard support.
  678.        Attempt to install xPC-Mouse in memory failed, because the driver
  679.        was compiled for 286 or better CPU, and this CPU tests out to be
  680.        8088 or 8086. Fix: Compile xpcmouse.asm with symbol XT set to
  681.        TRUE (see the ASM file). Use that xpcmouse.exe instead of the
  682.        present one. NB: The version in the distribution was compiled for
  683.        XT. We don't recommend a non-XT compile!
  684.  
  685.  
  686. ============================== PROBLEMS ==================================
  687.  
  688. If you leave Borland's TD386 with xPC-Mouse installed it hangs the
  689. computer. When MSDOS 5.0 came out Borland had to distribute a patch for
  690. TD386 because then the same problem occurred. So this seems to be not
  691. xPC-Mouse's problem but TD386's.
  692.  
  693. It has been reported that xPC-Mouse did not find the mouse driver. This
  694. happens with some old drivers. To solve this problem install a new mouse
  695. driver. A new mouse driver can be found on the Windows disks.
  696.  
  697. Loading xPC-Mouse from MS-Windows via a full screen DOS window is
  698. possible, but the system may lock up when EXIT is typed at the DOS
  699. prompt. Doing a normal "xpcmouse /U" should stop this from happening.
  700. Similar things happen with all TSR programs run in this manner from
  701. MS-Windows.
  702.  
  703. The use of xPC-Mouse with Kermit has been tested. There are many
  704. "gotchas" in using this interface with a remote unix system or remote
  705. DOS system. It is often necessary to turn off the mouse actions,
  706. sometimes the paste is off, sometimes the cursor key actions are off.
  707. This is especially true if your favorite editor supports the Xterm
  708. escapes, and you have decided to use that feature in the editor.
  709.  
  710.  
  711. =========================== KERMIT and RZ/SZ ===========================
  712.  
  713. This information is current in November 1994. Directory locations and
  714. FTP sites change with time.
  715.  
  716. To get a copy of MS Kermit 3.13 or later, use anonymous FTP to
  717. watsun.cc.columbia.edu. Hunt for the right ZIP file and download to your
  718. system.
  719.  
  720. Also recommended for fast uploads and downloads is SZ/RZ, invoked by
  721. program DSZ.COM from Omen Technology INC. The shareware version is
  722. available from oak.oakland.edu, in directory SimTel/msdos/zmodem.
  723.  
  724.  
  725. ============================= THE AUTHORS ================================
  726.  
  727. Jürgen G. Weber is now (1994) a student of computer science at the
  728. university of Stuttgart in southern Germany. He is also author of ZSIM,
  729. a Z80 - CP/M bios emulator that is available from ftp servers.
  730.  
  731. Grant B. Gustafson is professor of mathematics at the University of Utah
  732. in Salt Lake City. Besides xPC-Mouse, he has written text editors, C
  733. libraries, business programs and mathematical software.
  734.  
  735. Reproducable bugs in the operation of xPC-Mouse can be sent via email to
  736. the authors.
  737.  
  738.    Postcards and comments are welcome! This is free software!
  739.  
  740.    Jürgen G. Weber               GB Gustafson
  741.    Wiesentalstraße 1             113 JWB Math Dept Univ Utah
  742.    D-74523 Schwäbisch Hall       Salt Lake City, UT 84112
  743.    Germany - European Union      USA
  744.  
  745.    email: weberj@dia.informatik.uni-stuttgart.de
  746.    email: gustafson@math.utah.edu
  747.  
  748. =========== End of File xPC-Mouse. Last edited 16 Dec 1994. ============
  749.